LCORE-1019: Split auth.md into modular documentation structure #1047
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Reorganize authentication documentation from single 368-line file into dedicated docs/auth/ directory with focused files for each auth module. Expanded rh-identity documentation with User/System identity types, entitlement validation, request examples, and troubleshooting guide. Enhanced examples/lightspeed-stack-rh-identity.yaml with comprehensive comments and testing instructions. Signed-off-by: Major Hayden <major@redhat.com>
Contributor
WalkthroughThis PR reorganizes authentication documentation from a monolithic file into modular documentation pages. The main docs/auth.md file is refactored to provide navigation links to dedicated pages covering noop, Kubernetes, JWT token, API key token, Red Hat Identity authentication modules and authorization system. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
🎯 2 (Simple) | ⏱️ ~15 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/auth/api-key-token.md`:
- Around line 57-63: The example YAML uses the wrong env var syntax; update the
snippet under authentication -> module: api-key-token and api_key_config ->
api_key to use the format expected by replace_env_vars(), i.e. ${env.VAR_NAME}
(change ${API_KEY} to ${env.API_KEY}) so the configuration loader will correctly
substitute the environment variable.
🧹 Nitpick comments (1)
docs/auth/index.md (1)
45-47: Add language identifier to code block.For better rendering and to satisfy markdown linting, consider adding a language identifier to the code block. For ASCII art diagrams, use
text:-``` +```text Request → Authentication Module → User Identity → Role Resolution → Access Check → Endpoint</blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Comment on lines
+57
to
+63
| 2. **Store keys securely**: Use environment variables or secret management | ||
| ```yaml | ||
| authentication: | ||
| module: api-key-token | ||
| api_key_config: | ||
| api_key: ${API_KEY} # From environment variable | ||
| ``` |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find configuration loading code and environment variable handling
echo "=== Searching for configuration loader implementations ==="
rg -n "yaml|load.*config|environ|getenv|VAR" --type py -g "*.py" | head -50
echo -e "\n=== Looking for specific config/loader files ==="
fd -e py -e yaml | grep -E "(config|load|auth)" | head -20
echo -e "\n=== Checking main entry points ==="
fd -e py | xargs grep -l "yaml\|config" | head -10Repository: lightspeed-core/lightspeed-stack
Length of output: 6111
🏁 Script executed:
#!/bin/bash
# Find the actual load_configuration implementation and environment variable handling
echo "=== Finding load_configuration method ==="
rg -n "def load_configuration" --type py -B2 -A10
echo -e "\n=== Check api_key_token.py for env var handling ==="
rg -n "environment\|environ\|getenv\|\${" --type py src/authentication/api_key_token.py -A2 -B2
echo -e "\n=== Look for any environment variable substitution functions ==="
rg -n "substitute\|interpolate\|expand.*env" --type py
echo -e "\n=== Check how YAML is loaded in main config ==="
rg -n "yaml.load\|safe_load" --type py -B3 -A3 | head -40Repository: lightspeed-core/lightspeed-stack
Length of output: 1224
🏁 Script executed:
#!/bin/bash
# Find replace_env_vars function implementation
echo "=== Find replace_env_vars import and definition ==="
rg -n "replace_env_vars|from.*import.*replace" --type py -B2 -A10
echo -e "\n=== Search for def replace_env_vars ==="
rg -n "def replace_env_vars" --type py -A20
echo -e "\n=== Check for regex or pattern matching env vars ==="
rg -n "\\\$\{|environ\|getenv" --type py -B3 -A3Repository: lightspeed-core/lightspeed-stack
Length of output: 5535
🏁 Script executed:
#!/bin/bash
# Find examples and tests showing how replace_env_vars works
echo "=== Search for test cases with environment variables ==="
rg -n "replace_env_vars|API_KEY|\\\$\{" --type py tests/ -A3 -B1 | head -60
echo -e "\n=== Look for example configuration files with env vars ==="
find . -name "*.yaml" -o -name "*.yml" | xargs grep -l "API_KEY\|\\\$\{" 2>/dev/null
echo -e "\n=== Check example configuration files ==="
ls -la examples/
cat examples/lightspeed-stack-api-key-auth.yaml 2>/dev/null | head -40Repository: lightspeed-core/lightspeed-stack
Length of output: 3273
🏁 Script executed:
#!/bin/bash
# Search for actual environment variable usage patterns in config files
echo "=== Search all YAML files for environment variable patterns ==="
find . -name "*.yaml" -o -name "*.yml" | xargs grep -h "^\|" 2>/dev/null | sort -u | head -20
echo -e "\n=== Look for any test configurations with env vars ==="
find tests/ -name "*.yaml" -o -name "*.yml" | xargs cat 2>/dev/null | grep -E "\$|API_KEY|env" -B2 -A2
echo -e "\n=== Check if llama_stack is in requirements/dependencies ==="
find . -name "requirements*.txt" -o -name "pyproject.toml" -o -name "setup.py" | xargs grep -l "llama.stack\|llama_stack" 2>/dev/null
echo -e "\n=== Check pyproject.toml for llama_stack version info ==="
cat pyproject.toml 2>/dev/null | head -100Repository: lightspeed-core/lightspeed-stack
Length of output: 50388
Update example to use correct environment variable syntax.
The documentation shows ${API_KEY} but the correct syntax is ${env.API_KEY} with the env. prefix. The llama-stack configuration loader's replace_env_vars() function expects environment variables in the format ${env.VAR_NAME}.
Update the example to:
authentication:
module: api-key-token
api_key_config:
api_key: ${env.API_KEY} # From environment variable🤖 Prompt for AI Agents
In `@docs/auth/api-key-token.md` around lines 57 - 63, The example YAML uses the
wrong env var syntax; update the snippet under authentication -> module:
api-key-token and api_key_config -> api_key to use the format expected by
replace_env_vars(), i.e. ${env.VAR_NAME} (change ${API_KEY} to ${env.API_KEY})
so the configuration loader will correctly substitute the environment variable.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Reorganize authentication documentation from a single 368-line file into a dedicated
docs/auth/directory with focused files for each authentication module. This makes the documentation easier to navigate and maintain.New structure:
docs/auth/index.md- Overview, configuration basics, module selection guidedocs/auth/noop.md- noop & noop-with-token modulesdocs/auth/kubernetes.md- K8s/OCP authenticationdocs/auth/jwk-token.md- JWT/OAuth2 with role extractiondocs/auth/api-key-token.md- Static API key authdocs/auth/rh-identity.md- Expanded Red Hat Identity auth documentationdocs/auth/authorization.md- Role resolution & access rulesrh-identity expansion includes:
The original
docs/auth.mdis retained as a redirect page to maintain existing links.Type of change
Tools used to create PR
Related Tickets & Documents
Checklist before requesting a review
Testing
This is a documentation-only change. Testing steps:
docs/auth.md) still works via redirectSummary by CodeRabbit
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.